home *** CD-ROM | disk | FTP | other *** search
/ Die Speccy' 97 / Die Speccy' 97.iso / amiga_system / the_aminet / comm / fido / smartpoll.lha / SmartPoll.Man < prev    next >
Text File  |  1995-09-16  |  12KB  |  286 lines
  1.  
  2.                ********************************************
  3.  
  4.                               SmartPoll.rexx
  5.  
  6.                                 Version 1.3
  7.  
  8.                     An advanced poll script for points
  9.  
  10.                  Public domain in 1995 by Magnus Holmgren
  11.  
  12.                ********************************************
  13.  
  14.  
  15. 1. Introduction
  16. ===============
  17.  
  18.  SmartPoll.rexx is mainly intended for points that either have several
  19. bosses, and/or boss(es) with several lines, but it is still useful for
  20. other points, that send filerequests/crash mail to other nodes. It can call
  21. any number of bosses, with any number of lines, in a rotating manner. It
  22. will exit when a successfull call to each boss have been made. It can also
  23. handle crash/direct/normal mail and filerequests to any node (in your
  24. nodelist). It also supports AKAs, and can ignore certain nodes.
  25.  
  26.  
  27. 2. Requirements
  28. ===============
  29.  
  30.  In order to use this poll script, you need some software properly
  31. installed:
  32.  
  33.  ╖ ARexx. :) This includes rexxsupport.library.
  34.  ╖ RexxReqTools (for the requesters).
  35.  ╖ TrapDoor (a registered copy).
  36.  ╖ traplist.library and a (partial) nodelist (for the outbound scanning).
  37.  
  38.  
  39. 3. Installation
  40. ===============
  41.  
  42.  Simply copy the script to some drawer you find convenient (e.g. "Rexx:").
  43. Then you need to do some configuring. I suggest you don't edit the script,
  44. but instead make use of the configuration file. The default is
  45. "Mail:SmartPoll.cfg", but this can easily be changed. Simply use a text
  46. editor to write it (note: you can use tabs, since the script will translate
  47. any tabs found into spaces before processing it). See chapter 5
  48. (Configuration) for more information about the configuration.
  49.  
  50.  In this archive there is also a file called SmartPoll.comp.rexx. This is
  51. the SmartPoll.rexx file passed through a "Rexx compressor", that removes
  52. all comments, and joins as many commands as possible to one line, to make
  53. the ARexx parsing (somewhat) faster (and the file quite a bit smaller).
  54.  
  55.  
  56. 4. Usage
  57. ========
  58.  
  59.  It is very simple to use SmartPoll.rexx. Simply start it, with an optional
  60. name of the configuration file. If no name is specified, it will default to
  61. "Mail:SmartPoll.cfg" (for backward compatibility, "Mail:Poll.cfg" is also
  62. checked if "Mail:SpartPoll.cfg" doesn't exist). The script will then read
  63. the configuration, an associated data file, and perhaps scan your outbound
  64. directory, and finally start TrapDoor (if needed) and try to call all nodes.
  65.  
  66.  If a console window is opened, then you can stop the script by pressing
  67. Ctrl-C in that window. If you want to stop polling a certain node, the
  68. press Esc in one of the TrapDoor windows when that node is called. A
  69. requester will appear, asking you if you would like to continue polling the
  70. node.
  71.  
  72.  The file "Mail:SmartPoll.data" (previously known as "Mail:Poll.data") is a
  73. data file that this script needs in order to know which bosses that should
  74. be polled a certain day. You don't need to do anything about this file, the
  75. script handles it by itself.
  76.  
  77.  
  78. 5. Configuration
  79. ================
  80.  
  81.  The configuration file for SmartPoll.rexx is a simple text file with
  82. certain "configuration commands" (similar to the TrapDoor configuration
  83. file). Only one configuration command per line. Each command need at least
  84. one argument. Empty lines, or lines that start with the char "#" are
  85. ignored (i.e. they are comments). The following commands exists:
  86.  
  87.  AKA         - This command specifies AKAs. This way, SmartPoll can
  88.                properly recognize e.g. packets for another net when using
  89.                the "POLL NORMAL" command. This command expects two
  90.                arguments: The number of your boss, and the AKA it is also
  91.                known as (in that order). The node number of your boss
  92.                should be one of the nodes specified with the NODE command.
  93.  
  94.  ASK         - This command specifies if the script should ask you if it
  95.                should (keep) poll(ing) a certain node. If "NO", then all
  96.                nodes found in the outbound (even if they weren't due for
  97.                polling) will be added to the poll list. Also, if certain
  98.                errors occur (or there is no answer), then that node will be
  99.                excluded from further polling (during that session). If
  100.                "YES", then the script will ask you on how to act.
  101.  
  102.                If you use SmartPoll unattended (e.g. from a Cron script
  103.                during night), you should definitively set this to "NO".
  104.  
  105.  CONSOLE     - Name of the console. In this window SmartPoll.rexx will
  106.                print some information output during the polling. Default is
  107.                "Con:0/14/640/100/Poll.rexx/SCREEN TrapDoor". Use "Nil:" (or
  108.                "Null:", if you have it) to disable this.
  109.  
  110.  ERRORLIMIT  - When TrapDoor have returned certain errors for a node the
  111.                number of times specified here, then a requester will
  112.                appear, asking if you should continue polling the node.
  113.                Default is 5.
  114.  
  115.  IGNORE      - Any files found in OUTBOUND for this node will be silently
  116.                ignored. Nice to have if you use e.g. AmiGate.
  117.  
  118.  NODE        - Here you specify your boss(es). The argument string should
  119.                look like this (argument enclosed in "<>" are required, "[]"
  120.                are optional):
  121.  
  122.                <Days> <Boss> [Phone... [PW=Password]]
  123.  
  124.                They "Days" argument specifies how often this boss should be
  125.                polled. Use 0 for each time SmartPoll.rexx is started, 1 for
  126.                every day, 2 for every other day etc. The current system date
  127.                is used to keep track of this.
  128.  
  129.                "Boss" specifies the node number of your boss.
  130.  
  131.                "Phone" is the phonenumber(s) of your boss. A number may not
  132.                contain spaces. You can add any number of phonenumbers, and
  133.                SmartPoll.Rexx will try each one in a rotating manner. If
  134.                you don't have a nodelist (for your boss(es)), then you must
  135.                specify a phonenumber.
  136.  
  137.                The "Password" must be the last word on the line, and is
  138.                indicated by a "PW=" in front of it. This is needed if you
  139.                don't have a nodelist and poll several bosses (or if you
  140.                haven't installed the passwords with TrapList).
  141.  
  142.                Note: Earlier versions of SmartPoll didn't handle passwords
  143.                properly for custom phonenumbers. SmartPoll will now try to
  144.                find the password for all nodes, if not specified, and
  145.                traplist.library is available.
  146.  
  147.                You may specify as many bosses as you like.
  148.  
  149.  OUTBOUND    - The name of your outbound drawer. Default is "Mail:Outbound".
  150.  
  151.  POLL        - This specifies what files the outbound scanner should include
  152.                (or not include) in the poll list. The following arguments
  153.                may be specified (in any number and/or order, the last of a
  154.                certain type is used):
  155.  
  156.                CRASH     - Include crash mail.
  157.                NOCRASH   - Don't include crash mail (default).
  158.                DIRECT    - Include direct mail.
  159.                NODIRECT  - Don't include direct mail (default).
  160.                NORMAL    - Include normal mail.
  161.                NONORMAL  - Don't include normal mail (default).
  162.                REQUEST   - Include file requests.
  163.                NOREQUEST - Don't include file requests (default).
  164.  
  165.                The (NO)NORMAL argument is useful, since you can configure to
  166.                call a boss, say, every third day. By adding "NORMAL", you can
  167.                "force" a poll if the outbound should happen to hold any mail
  168.                for that boss.
  169.  
  170.                If all types are disabled (the default), then the outbound
  171.                drawer will not be scanned.
  172.  
  173.                A nodelist (and traplist.library) is required for this
  174.                feature to work.
  175.  
  176.  PUBSCREEN   - The name of the public screen on which requesters should
  177.                appear on. Default is "TrapDoor" (if this screen doesn't
  178.                exist, then the default public screen will be used instead).
  179.  
  180.  REDAILDELAY - The redail delay, specified in seconds. Default is 30. After
  181.                each "dialing" round, SmartPoll.rexx will wait this time
  182.                before restarting the dialing. This only happens if there is
  183.                at least one node that haven't been called yet.
  184.  
  185.  REXXNAME    - The name of the TrapDoor ARexx port. Default is "TrapDoor".
  186.  
  187.  TDCMD       - The command used to start TrapDoor, if this is needed. The
  188.                arguments "REXXNAME" (using what was configured with the
  189.                REXXNAME command) and "ANSWER" will be added to this string.
  190.                This string should include the full path to TrapDoor, if
  191.                this is needed, plus any additional configuration commands
  192.                you like. Default is "TrapDoor".
  193.  
  194.                If TrapDoor was started by SmartPoll, it will also send a
  195.                "QUIT" command to TrapDoor when it exits.
  196.  
  197.  
  198. 6. Known problems
  199. =================
  200.  
  201.  If files in the outbound drawer have spaces in their names then this
  202. script might get confused. However, SmartPoll checks the filename suffix
  203. (and ignores files without a proper suffix), so there shouldn't be any
  204. problems.
  205.  
  206.  This script seems stable in everyday usage, but since I haven't tested all
  207. features that carefully, bugs/quirks may remain.
  208.  
  209.  
  210. 7. The future
  211. =============
  212.  
  213.  The current version suits my needs rather well. However, it isn't the most
  214. user friendly program (to interact with the actual polling is a bit
  215. tricky). Thus, a possible future "extension" could be a rewrite into C,
  216. with a nice user interface (perhaps something similar to TrapDispatcher).
  217. However, I currently have no time for such a thing. I personally don't
  218. really need it, and there are other projects that I feel are more important.
  219.  
  220.  
  221. 8. Author
  222. =========
  223.  
  224.  This script was written by Magnus Holmgren. Comments, questions etc., can
  225. be sent to:
  226.  
  227.     Magnus Holmgren
  228.     KvarnbergsvΣgen 5
  229.     S-444 47  Stenungsund
  230.     SWEDEN
  231.  
  232.     Fidonet:  "Magnus Holmgren" @ 2:204/204.6
  233.  
  234.  
  235. 9. Version history
  236. ==================
  237.  
  238.  Version 1.0:
  239.  
  240.   ╖ Initial release
  241.  
  242.  
  243.  Version 1.1:
  244.  
  245.  ╖ Forgot to initialize a stem-item, causing problems when polling
  246. "non-bosses".
  247.  
  248.  
  249.  Version 1.2:
  250.  
  251.  ╖ When "Skip"ing a node found in the outbound, the requester could be
  252. repeated (since there may be more than one file for a certain node).
  253. Delete also handle the extra files.
  254.  
  255.  ╖ Fixed the spelling error of the "REDIALDELAY" command. The old command
  256. ("REDAILDELAY") is still supported for backward compatibility.
  257.  
  258.  ╖ Fixed a few requester messages in the polling loop. Didn't use a proper
  259. linefeed char.. :)
  260.  
  261.  ╖ "Polling around midnight" problem fixed. Now it checks all dates before
  262. starting to poll. That way, if SmartPoll is started a little before
  263. midnight (usually to poll a node or two that wasn't polled yet), then the
  264. script won't poll the other nodes after the time passes midnight (and
  265. making the polling the next day "impossible" (without changing the data
  266. file)).
  267.  
  268.  
  269.   Version 1.3:
  270.  
  271.   ╖ Added the "AKA" command.
  272.  
  273.   ╖ Added the "IGNORE" command. Nice if you use AmiGate.
  274.  
  275.   ╖ SmartPoll will now try to find a password for nodes with custom phone
  276. numbers. In earlier versions, I assumed that sending the "BOSS" Rexx
  277. command to TrapDoor was enough. It turned out it wasn't. This caused
  278. problems that were difficult to understand at first (the connection "error"
  279. message from TrapDoor was,nt very informative ;).
  280.  
  281.   ╖ The default configuration name now is 'Mail:SmartPoll.cfg'. However,
  282. SmartPoll will still read the 'Mail:Poll.cfg' file, in case the new name
  283. can't be found. Also, the datafile have been renamed similarly. I haven't
  284. bothered to support the old name (no need).
  285.  
  286.